Modernize explanation of `build.rs`

After some recent head-banging, it was explained to me that `"build.rs"` is a special file name, and that Cargo will build such a file even if you do not expect it to, for example if `Cargo.toml` contains the commented out line

```
#build = "build.rs"
```

Some experimentation lead me to the described behavior, but if it misses any subtle details please feel free to correct. The old text is incorrect, though.

diff --git a/src/doc/build-script.md b/src/doc/build-script.md
index a0bfe0fd669ca3a92391b1d8ee12affa4b433ace..61bbcd708e67919eddd2273185f893b64c1bce25 100644 (file)
--- a/src/doc/build-script.md
+++ b/src/doc/build-script.md
@@ -18,9 +18,9 @@ build = "build.rs"
 
 The Rust file designated by the `build` command (relative to the package root)
 will be compiled and invoked before anything else is compiled in the package,
-allowing your Rust code to depend on the built or generated artifacts. Note
-that there is no default value for `build`, it must be explicitly specified if
-required.
+allowing your Rust code to depend on the built or generated artifacts. Note that 
+if you do not specify a value for `build` but your package root does contains a 
+`"build.rs"` file, Cargo will compile and invoke this file for you.
 
 Some example use cases of the build command are: